Workaround: Global hotkeys on Wayland in Teamspeak 6

Wayland support keeps getting better with each passing month. Still, some gaps remain either in application compatibility or in specific Wayland compositor implementations. One of a common issues users encounter is lack of global keyboard shortcut support. On Wayland applications don’t have direct access to the keyboard input when not focused. This is a security feature that is designed to prevent compromised applications from running a key logger. However, it interferes with an application ability to implement keyboard shortcuts that can be triggered globally.

Fortunately, there is a protocol for desktop environments to provide access to shared capabilities such as keyboard bindings in a safe and controller manner. Specifically, for global keyboard shortcuts support there is Global Hotkeys portal part of xdg-desktop-portal specification.

At the time of writing the support for Global Hotkeys is still quite patchy, Teamspeak 6 doesn’t use it. However, there is way around it. Teamspeak 6 exposes Remote Apps API that can be used to control some aspects of the application. It allows an external application to connect to Teamspeak via websockets and trigger a selected action.

To be precise, the API doesn’t allow you to trigger an action directly. Instead, it can be used to simulate virtual key presses, which then can be bound to an action in Teamspeak UI the same was as a regular key press coming from a real keyboard.

The solution #

Using the Remote Apps API we can create a simple CLI app that sends key triggers to Teamspeak. Then we can bind one of these triggers to an action such as toggling mute. The only missing piece is how to execute the app when a chosen key is pressed.

Fortunately, it shouldn’t be a problem. Modern desktop environments allow users to define custom shortcuts that can execute any command or application on the local system.

Here is how to set it up in Gnome: Gnome Keyboard Shortcuts For Hyprland look here - Hyprland Binds.

As for KDE Plasma, it should also be possible though I couldn’t find an official documentation page to point to.

What’s important is that these keyboard shortcuts are globally available regardless of which application is currently focused.

tshotkeytrigger CLI app #

I’ve created a simple CLI application that can trigger a hotkey binding in Teamspeak - tshotkeytrigger.

Once installed you can run the following command to set up a hotkey for toggling microphone mute.

tshotkeytrigger --button-id toggle.mute --setup

Just before you start ensure that Teamspeak is running and Remote Apps are enabled (Settings -> Remote Apps -> Enabled).

The application will walk you through creating a new trigger during setup process.

Then create a global shortcut in your desktop environment as explained in a previous section to run tshotkeytrigger command:

tshotkeytrigger --button-id toggle.mute

I’ve been running this setup for months without any issues.